Translation at the Carpentries:

How to translate?

Challenges in technical translation

• Need to be able to
  • update translation when original changes
  • deal with source code vs. rendered version
• Most solutions for translating source code (gettext and PO files) are designed with software in mind, not prose text

PO files

What is technical translation anyways?

Past approach (“Styles” format)

• The current Carpentries lesson format is called the “Styles” format

Past approach (“Styles” format)

• The current Carpentries lesson format is called the “Styles” format

• The Styles format is based on Jekyll (and some other tools)

• Translation system* designed by David Pérez-Suárez used a tool called PO4gitbook

PO4gitbook

• All translations controlled from a central repo with submodules for each lesson (can track changes)

• Rendering not possible by typical translator; required David PS to update each time

• No standard system for how to localize

  • transifex (cloud-based)
  • POedit (local text editor)
  • github (online code review; used by JA community)

New approach (“Workbench” format)

• The upcoming Carpentries lesson format is the “Workbench” format

New approach (“Workbench” format)

dovetail

• Each translation is contained within each lesson¹

• Rendering is easily accomplished locally by the translator

• Plan to have a standard system for translation (e.g., pushing/pulling from transifex)

dovetail

library(dovetail)

# Copy (untranslated) files needed for rendering lesson
create_locale("ja")

# Create PO files ----
create_po_for_locale("ja")

# Edit PO files ----
# for example, with
# usethis::edit_file("po/ja/01-introduction.po")

# Translate md files ----
# translate all (R)md files at once to `./locale/{lang}/`
translate_md_for_locale("ja")

# Build translated lesson ----
sandpaper::build_lesson("locale/ja/")

dovetail

Output of translation

|-- CONTRIBUTING.md             # - Carpentries Rules for Contributions
|-- README.md                   # - Describes lesson
...
|-- po                          # - NEW, contains PO files for translation
|   `-- ja/                     
|       |-- 00-introducition.po 
|       |-- CONTRIBUTING.po     
|       |...                    
|-- locale                      # - NEW, contains translated files
|   `-- ja/                     
|       |-- CONTRIBUTING.md     # - NEW, translated markdown files
|       |-- site/               # - NEW, translated, rendered site
|           |-- built/          
|           |...               

dovetail design philosophy

• Make it easier for maintainer to maintain (i18n)
  • Not dependent on one person maintaining one central repo
• Make it easier for translators to translate (l10n)
  • Requires minimal technical knowlege to participate (don’t need git)